DigiLocker Webhook

The following document highlights the details of the DigiLocker Webhook.

Overview

The DigiLocker webhook notifies your application when a user completes or cancels the DigiLocker consent flow. It triggers automatically once the user finishes the consent process. To receive webhook notifications, simply register your webhook URL with HyperVerge.

Webhook Events

The webhook delivers notifications for the following user actions:

• User grants consent: The user completes the DigiLocker journey and grants access to their documents.
• User denies or cancels: The user explicitly cancels the journey or denies access to documents.

IP Whitelisting

HyperVerge sends webhooks as HTTP POST requests to your registered URL. For those requests to reach your endpoint, you must permit inbound traffic from HyperVerge's source IPs (in your firewall, load balancer, or security group). The following are the source IPs:

65.0.82.147
3.7.90.248
3.6.33.64

Configuration URL

Register the URL where you want to receive notifications using the following API:

https://api.hyperverge.co/api/digilocker/webHook

URL requirement

The URL you register must be a publicly accessible HTTPS endpoint so that HyperVerge can deliver webhooks to it.

Method(s)

• POST : Store webhook configuration (register your webhook URL)
• GET : Retrieve current webhook configuration

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
Content-Type	Mandatory (POST Method only)	Defines the media type for the request payload. Required when storing webhook configuration (POST).	application/json

Inputs

The following table provides the details of the parameters required for the POST request (store configuration):

Parameter	Mandatory or Optional	Description
url	Mandatory	The HTTPS URL that will receive webhook events. Must be publicly accessible. Register this URL before initiating any DigiLocker journeys.

Request

The following code snippets demonstrate the Webhook configuration requests.

Store webhook configuration (POST)

curl -X POST 'https://api.hyperverge.co/api/digilocker/webHook' \
  -H 'appId: <Enter_the_HyperVerge_appId>' \
  -H 'appKey: <Enter_the_HyperVerge_appKey>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-webhook-url.com/endpoint"
  }'

Retrieve webhook configuration (GET)

curl -X GET 'https://api.hyperverge.co/api/digilocker/webHook' \
  -H 'appId: <Enter_the_HyperVerge_appId>' \
  -H 'appKey: <Enter_the_HyperVerge_appKey>'

Responses

The following code snippets are the HTTP responses from the Configuration API. For the JSON that HyperVerge sends to your URL when an event occurs, see Webhook Payload.

POST response (200 - Success)

Returned when you successfully store your webhook URL.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "message": "Config added successfully"
  }
}

GET response (200 - Success)

Returned when you successfully retrieve your current webhook configuration.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "appid": "your-app-id",
    "webHookUrl": "https://client-webhook-url.com/endpoint"
  }
}

Webhook Payload

When a DigiLocker consent event occurs, the Digilocker webhook sends one of the following four payloads (JSON) to the URL you registered.

User consent granted

Sent when the user successfully completes the DigiLocker journey and grants consent.

{
  "refId": "unique-reference-id-from-client",
  "event": {
    "name": "digilocker.user.consent.granted",
    "code": "user_granted_consent"
  },
  "timeStamp": "2024-01-15T10:30:45.123Z"
}

User cancelled

Sent when the user explicitly cancels the DigiLocker consent process.

{
  "refId": "unique-reference-id-from-client",
  "event": {
    "name": "digilocker.user.denied",
    "code": "user_cancelled"
  },
  "timeStamp": "2024-01-15T10:30:45.123Z"
}

User denied consent

Sent when the user explicitly denies access to documents during the consent flow.

{
  "refId": "unique-reference-id-from-client",
  "event": {
    "name": "digilocker.user.denied",
    "code": "user_denied_consent"
  },
  "timeStamp": "2024-01-15T10:30:45.123Z"
}

Default denied

Sent when the consent process ends without success for any other reason (default denied state).

{
  "refId": "unique-reference-id-from-client",
  "event": {
    "name": "digilocker.user.denied",
    "code": "user_cancelled_or_denied_consent"
  },
  "timeStamp": "2024-01-15T10:30:45.123Z"
}

Payload Details

The following table provides the details of the parameters in the Webhook payload:

Parameter	Type	Description
refId	string	The reference ID that uniquely identifies the user session, matching the refId you provide in /digilocker/start API call. This implements idempotency when handling duplicate deliveries.
event	object	The object contains event details (name and code)
event.name	string	The name of the event. Possible values: digilocker.user.consent.granted digilocker.user.denied See Event names and codes for more details
event.code	string	The specific code for the event. Possible values: user_granted_consent user_cancelled user_denied_consent user_cancelled_or_denied_consent See Event names and codes for more details
timeStamp	string (ISO 8601)	Timestamp when the event occurred

Event names and codes

The following table lists all possible combinations of event.name and event.code and when each is triggered:

event.name	event.code	Trigger
digilocker.user.consent.granted	user_granted_consent	User completes the DigiLocker journey and grants consent
digilocker.user.denied	user_cancelled	User explicitly cancels the DigiLocker consent process
digilocker.user.denied	user_denied_consent	User explicitly denies access to documents during the consent flow
digilocker.user.denied	user_cancelled_or_denied_consent	Default denied state when the consent process ends without success for any other reason

Support

For additional details on the DigiLocker webhook, please contact our support team at support@hyperverge.co.